Developer Documentation

QuickTime 4 API Documentation

3D Graphics Programming with QuickDraw 3D 1.5.4

Previous | QD3D Book | Overview | Chapter Contents | Next |

Managing Shared Objects

QuickDraw 3D provides routines that you can use to get a reference to a shared object or to get the type of a shared object.

Q3Shared_GetReference

You can use the Q3Shared_GetReference function to get a reference to a shared object.

TQ3SharedObject Q3Shared_GetReference (TQ3SharedObject sharedObject);
sharedObject
A shared object.

DESCRIPTION

The Q3Shared_GetReference function returns, as its function result, a reference to the shared object specified by the sharedObject parameter. You can use this function to prevent QuickDraw 3D from deleting an object twice.

ERRORS

kQ3ErrorNULLParameter kQ3ErrorInvalidObjectParameter

Q3Shared_IsReferenced

You can use the Q3Shared_IsReferenced function to determine whether a shared object has more than one reference to it.

TQ3Boolean Q3Shared_IsReferenced (TQ3SharedObject sharedObject);
sharedObject
A shared object.

DESCRIPTION

The Q3Shared_IsReferenced function returns, as its function result, a Boolean value that indicates whether the shared object specified by the sharedObject parameter has more than one reference to it ( kQ3True ) or has only one reference to it ( kQ3False ).

The Q3Shared_IsReferenced function is intended for use by an application or other code that needs to determine whether it has the only existing reference to a shared object.

SPECIAL CONSIDERATIONS

You should never call Q3Shared_IsReferenced as follows:

while (Q3Shared_IsReferenced(mySharedObject)) {
    Q3Object_Dispose(mySharedObject);
}

This code will cause your application to crash.

ERRORS

kQ3ErrorNULLParameter kQ3ErrorInvalidObjectParameter

Q3Shared_GetType

You can use the Q3Shared_GetType function to get the type of a shared object.

TQ3ObjectType Q3Shared_GetType (TQ3SharedObject sharedObject);
sharedObject
A shared object.

DESCRIPTION

The Q3Shared_GetType function returns, as its function result, the type identifier of the shared object specified by the sharedObject parameter. If successful, Q3Shared_GetType returns one of these constants:

kQ3SharedTypeAttachment
kQ3SharedTypeControllerState
kQ3SharedTypeDrawContext
kQ3SharedTypeFile
kQ3SharedTypeReference
kQ3SharedTypeRenderer
kQ3SharedTypeSet
kQ3SharedTypeShape
kQ3SharedTypeShapePart
kQ3SharedTypeStorage
kQ3SharedTypeString
kQ3SharedTypeTexture
kQ3SharedTypeTracker
kQ3SharedTypeViewHints

If the type cannot be determined or is invalid, Q3Shared_GetType returns the value kQ3ObjectTypeInvalid .

ERRORS

kQ3ErrorNULLParameter kQ3ErrorInvalidObjectParameter

Q3Shared_GetEditIndex

You can use the Q3Shared_GetEditIndex function to get the edit index for a shared object.

unsigned long Q3Shared_GetEditIndex (TQ3SharedObject sharedObject);
sharedObject
A shared object.

DESCRIPTION

The Q3Shared_GetEditIndex function returns, as its function result, the current edit index of the shared object specified by the sharedObject parameter. An edit index is a unique number associated with a shared object that changes each time the object is edited. You can use the edit index to determine whether an object you are caching has changed since the object was cached, using code such as the following:

struct -> editIndex = Q3Shared_GetEditIndex(foo);
struct -> object = Q3Shared_GetReference(foo);

Later you can determine if the object has been edited:

if (struct->editIndex !=
        Q3Shared_GetEditIndex(struct->object)) {
                /* Has been edited -- update or re-create caches. */
} else {
                /* Not edited */
    }

SEE ALSO

Use the Q3Shared_Edited function to manually change an object's edit index.

ERRORS

kQ3ErrorNULLParameter kQ3ErrorInvalidObjectParameter kQ3ErrorInvalidObjectType

Q3Shared_Edited

You can use the Q3Shared_Edited function to change a shared object's edit index.

TQ3Status Q3Shared_Edited (TQ3SharedObject sharedObject);
sharedObject
A shared object.

DESCRIPTION

The Q3Shared_Edited function changes the edit index of the shared object specified by the sharedObject parameter. This function is designed for use by shared plug-in objects; those objects should call Q3Shared_Edited whenever their private data changes.

ERRORS

kQ3ErrorNULLParameter kQ3ErrorInvalidObjectParameter

© 1997 Apple Computer, Inc.

Previous | QD3D Book | Overview | Chapter Contents | Next |